<!--

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<html>
<body>
<h1>jDBI 1.4 Documentation</h1>
<ul>
    <li><a href="http://jdbi.codehaus.org/">Home</a></li>
    <li><a href="http://dist.codehaus.org/jdbi/jdbi-1.4.5.tar.gz">jDBI 1.4.5 Source Tarball</a></li>
    <li><a href="http://dist.codehaus.org/jdbi/jdbi-1.4.5.zip">jDBI 1.4.5 Source Zip</a></li>
    <li><a href="http://dist.codehaus.org/jdbi/jdbi-1.4.5.jar">jDBI 1.4.5 Standalone Jar</a></li>
    <li><a href="http://dist.codehaus.org/jdbi/">All Downloads</a></li>
    <li><a href="http://jira.codehaus.org/browse/JDBI">Issue Tracker</a></li>
    <li><a href="http://www.opensource.org/licenses/apache2.0.txt">License (ASL 2.0)</a></li>
    <li><a href="mailto:user-subscribe@jdbi.codehaus.org">Subscribe to Users List</a></li>
    <li><a href="mailto:dev-subscribe@jdbi.codehaus.org">Subscribe to Developers List</a></li>
    <li><a href="http://svn.codehaus.org/jdbi/">Browse Subversion</a></li>
    <li><a href="http://svn.jdbi.codehaus.org/">Browse Subversion with FishEye</a></li>
</ul>
<h2>Basics</h2>
<p>
    The entry point for the library is the <code>org.skife.jdbi.DBI</code>
    class. The <code>DBI</code> class is used to provide <code>Handle</code>
    instances, which are analogous to a JDBC <code>Connection</code>. Much
    like a <code>Connection</code>, a <code>Handle</code> will hold a
    connection to the database while it is open. <code>Handle</code> instances
    must be explicitely closed by the client to return, or close, the connection.
</p>

<p>
    The <code>DBI</code> can be used in one of two ways. The first is to use
    its static methods to directly open <code>Handle</code> instances. The second
    is to instantiate a <code>DBI</code> instance and use the instance to retrieve
    <code>Handle</code> instances. The second approach, instantiating the
    <code>DBI</code> has the advantage of allowing all of the <code>Handle</code>
    instances created by it to share a named statement cache, which can
    be convenient and improve performance.
</p>

<p>
    The <code>Handle</code> provides for two styles of usage. The first is a
    traditional statement execution and result set model. Usage here would
    look like:
</p>
<code><pre>
    List rows = handle.query("select name from foo where name like 'Brian@'");
    for (Iterator i = rows.iterator(); i.hasNext();) {
        Map row = (Map)i.next();
        System.out.println(row.get("name"));
    }
</pre></code>

<p>
    Alternately, a callback style interface can be used, where the above
    snippet would be expressed as:
</p>
<code><pre>
    handle.query("select name from foo where like 'Brian@'", new RowCallback() {
        public void eachRow(Handle handle, Map row) {
            System.out.println(row.get("name"));
        }
    });
</pre></code>

<p>
    In the callback, the query is executed in a single transaction, and throwing an exception
    from the callback will stop iteration, and abort the transaction. Speaking of transactions,
    the same type of callback or imperitive API is available for working with them, as well.
</p>

<h2>Queries</h2>

<p>
    The <code>Handle</code> provides three means of identifying SQL statements. The first is
    to provide the SQL directly to the query call:
</p>
<code><pre>
    List rows = handle.query("select name from foo where name like 'Brian@'");
</pre></code>

<p>
    The second is to name queries before calling them, and then call them by name:
</p>
<code><pre>
    handle.name("wombats!", "select name from foo where name like 'Brian@'");
    List rows = handle.query("wombats!);
</pre></code>

<p>
    The final means is to use externalized statements:
</p>
<code><pre>
    List rows = handle.query("squirrel");
</pre></code>

<p>
    Using an externalized statement requires having a text file with the name of the query,
    appended with <code>.sql</code> (<code>squirrel.sql</code> in this case), on the classpath.
    The query will be retrieved via <code>ClassLoader#getResource</code>. The query will only
    be loaded from the classpath once (usually, see the named statement cache docs) and stored
    as a named statement.
</p>

<p>
    In addition to the implicit external statement load, you can explicit load an external statement via:
</p>
<code><pre>
    handle.load("jackals");
</pre></code>

<p>
    The default behavior for finding queries is to look for a named query matching the string, then
    attempt to parse it as SQL, then to look for an external sql file.
</p>

<h3>Parameterized Queries</h3>

<p>
    jDBI support positional and named parameterized queries. Parameterized statements can be described
    in the form <code>select id, name from bar where id = ?</code> or <code>select id, name from bar
    where id = :id</code>. The advantage to using the second form is that you can then use named
    parameters to execute the statement, as well as positional.
</p>

<p>
    Executing a statement with named parameters requires passing in a map with the name
    ("id" in the above example) as a key, and the value to substitute as the matching value. Calling
    a positionally parameterized query involves passing in an object array, or collection, of arguments
    which will bind the elements to the statement in iteration order. There are convenience methods for
    common cases, as well as a convenient class for building maps of named arguments (<code>Args</code>).
</p>

<h2>Named Statement Cache</h2>

<p>
    If an instance of <code>DBI</code> is used to obtain <code>Handle</code> instances, all handles will
    share a named statement cache. This allows for only having to name, or load, queries once across all
    <code>Handle</code> instances obtained from a <code>DBI</code>. This can make a significant
    performance difference if externalized statements are used (no searching the classpath for each
    <code>Handle</code>), otherwise it is pretty much just a convenience.
</p>

<p>
    The <code>DBI</code> instance provides convenience methods for manipulating the named statement cache.
</p>

<p>
    You can join the <a href="mailto:user-subscribe@jdbi.codehaus.org">jdbi-users</a> or
    <a href="mailto:dev-subscribe@jdbi.codehaus.org">jdbi-dev</a> mailing lists if you have any questions.
    We're happy to help, and try hard to accomodate feature requests!
</p>
<!-- config -->
<h2>Configuration</h2>

<p>
    jDBI supports many configuration options via the various <code>org.skife.jdbi.DBI</code> constructors.
    The no-arg constuctor is worth mentioning, however, as it attempts to figure out how to best
    configure itself via looking for relevant properties.
</p>

<p>
    It first looks for an <code>org.skife.jdbi.properties-file</code> system property which
    represents a properties file to be loaded via the classpath. If that is not found, it looks
    for <code>jdbi.properties</code>, then <code>jdbc.properties</code>, then
    <code>dbi.properties</code>, then finally <code>database.properties</code> on the classpath.
    It will use the first it finds and stop looking for others once it finds one.
</p>

<p>
    Once a suitable configuration properties file has been loaded, jDBI will look for various
    properties used to configure it. There are multiple possible values for each logical
    property, and the order of preference if it should find multiple is the order listed here:
</p>
<table>
<tr>
    <td>
        <ul>
            <li>jdbi.url</li>
            <li>jdbc.url</li>
            <li>connection.string</li>
        </ul>
    </td>
    <td>
        JDBC Connection URL, ie <code>jdbc:derby:my_database</code>,
        required
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.driver</li>
            <li>jdbc.driver</li>
            <li>driver</li>
            <li>drive</li>
        </ul>
    </td>
    <td>
        JDBC Driver class name, ie <code>org.apache.derby.jdbc.EmbeddedDriver</code>,
        required
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.username</li>
            <li>jdbi.user</li>
            <li>jdbc.username</li>
            <li>jdbc.user</li>
            <li>username</li>
            <li>user</li>
        </ul>
    </td>
    <td>
        Username to be used when obtaining connections from the database, optional
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.password</li>
            <li>jdbi.pass</li>
            <li>jdbc.password</li>
            <li>jdbc.pass</li>
            <li>password</li>
            <li>pass</li>
        </ul>
    </td>
    <td>
        Password to be used when obtaining connections from the database, optional
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.transaction-handler</li>
            <li>jdbc.transaction-handler</li>
            <li>transaction-handler</li>
        </ul>
    </td>
    <td>
        <b>OPTIONAL</b> class name of a <code>TransactionHandler</code> which should
        be used to override default transaction handling. Must supply a no-arg constructor. Optional.
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.statement-locator</li>
            <li>jdbc.statement-locator</li>
            <li>statement-locator</li>
        </ul>
    </td>
    <td>
        <b>OPTIONAL</b> class name of a <code>StatementLocator</code> which should
        be used to override default (cached from classpath) external sql statement locating. Optional.
    </td>
</tr>
<tr>
    <td>
        <ul>
            <li>jdbi.handle-decorator-builder</li>
            <li>jdbc.handle-decorator-builder</li>
            <li>handle-decorator-builder</li>
        </ul>
    </td>
    <td>
        <b>Unstable Feature</b> class name of a <code>HandleDecoratorBuilder</code>
        to be used to decorate <code>Handle</code> instances obtained from the
        <code>DBI</code> instance instantiated. This feature is functionally stable,
        but the specific api may change somewhat while it remains offically unstable.
        Please read the notes regarding the <code>org.skife.jdbi.unstable</code> package
        before using this. Optional.
    </td>
</tr>
</table>
<!-- /config -->
<!-- unstable -->
<h2>Unstable Features</h2>

<p>
    Various features or interfaces may be exposed via packages in the the
    <code>org.skife.jdbi.unstable</code> package. These features or interfaces
    will be functionally stable (ie, should be bug free, and behave as expected, etc),
    but their exact interfaces, or exact behavior, is subject to change between releases
    because they are still being hammered out. The features are exposed to be used, and
    may certainly be used, but if you do use them be aware that you may need to make
    changes to the code using them between minor or bug fix releases.
</p>

<p>
    If you do rely on an officially unstable feature, please let us know so that we
    can attempt to make sure to not cause you harm, and so that we can prioritize
    the feature for interface stabilization to get it out of an <code>unstable</code>
    sub-package. If it is un <code>unstable</code> we think it is useful, and may be
    using it ourselves, but are probably just not convinced that the exact API is
    correct yet. Feedback is much appreciated!
</p>
</body>
</html>
